<!DOCTYPE html>

<html lang="en" data-content_root="../../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Hat blocks &#8212; Pytch  documentation</title>
    <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=03e43079" />
    <link rel="stylesheet" type="text/css" href="../../_static/classic.css?v=36340f97" />
    <link rel="stylesheet" type="text/css" href="../../_static/css/pytch-classic.css?v=0321735e" />
    
    <script src="../../_static/documentation_options.js?v=7f41d439"></script>
    <script src="../../_static/doctools.js?v=9bcbadda"></script>
    <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="icon" href="../../_static/favicon.ico"/>
    <link rel="author" title="About these documents" href="../../about.html" />
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="Syscalls" href="syscalls.html" />
    <link rel="prev" title="Threading model" href="threading-model.html" /> 
  </head><body>
<div class="NavBar">
  <a href="../../../app/"><h1>Pytch</h1></a>
  <ul>
    <a href="https://pytch.scss.tcd.ie/"><li>About Pytch</li></a>
    <a href="../../index.html"><li>Help</li></a>
    <a href="../../../app/tutorials/"><li>Tutorials</li></a>
    <a href="../../../app/my-projects/"><li>My projects</li></a>
  </ul>
</div>
<div class="warning-work-in-progress">
  <p>These help pages are incomplete — we are working on it!</p>
</div>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="hat-blocks">
<h1>Hat blocks<a class="headerlink" href="#hat-blocks" title="Link to this heading">¶</a></h1>
<p>This is how threads get launched in the first place. (Apart from code in
the <code class="docutils literal notranslate"><span class="pre">__init__()</span></code> of an Actor class, which runs when each <code class="docutils literal notranslate"><span class="pre">Actor</span></code>’s
instance-0 is created by Pytch.) As in Scratch, a section of code is
marked to indicate that the user wants it to be triggered when a certain
event occurs. In Pytch, this is done with Python decorators on the
methods.</p>
<p>The decorator itself just attaches an annotation to the function (at the
time of reading the class body, methods are just functions). This
annotation holds a list describing the decorators which have been used
on the function. Each descriptor is a pair (type, data); some types have
no data (green-flag); others do (receive, in which case data is message
string; keypress, key name).</p>
<p>At class registration time (register-sprite-class or -stage-), the
Project combs through the properties of the class object, looking for
functions which have the annotation. Pytch then maintains maps, to be
able to find which functions to call within which classes when a
particular event happens.</p>
<p>Some hat-blocks trigger for all instances of a <code class="docutils literal notranslate"><span class="pre">Sprite</span></code>; some just for
an ‘affected’ instance (this-clicked, start-as-clone). A ‘handler’ knows
which <code class="docutils literal notranslate"><span class="pre">Actor</span></code> it is for, and which unbound method to run when the
event happens. This is used for all-instance events (e.g.,
when-I-receive). More than one method can be decorated for the same
event, so Pytch gathers event-handlers into an event-handler-group. A
(JavaScript-side) <code class="docutils literal notranslate"><span class="pre">PytchActor</span></code> object stores a map from event to the
corresponding handler-group.</p>
<p>DOC TODO: Green flag vs when-I-recv vs clone; where are these event
handler maps stored?</p>
<section id="launching-threads-from-event">
<h2>Launching threads from event<a class="headerlink" href="#launching-threads-from-event" title="Link to this heading">¶</a></h2>
<p>When an event occurs: The handler creates a thread per instance of the
class; the handler-group gathers all such threads for all its contained
handlers. The <code class="docutils literal notranslate"><span class="pre">Project</span></code> gathers all such threads across all its
registered actors. The result is a ‘thread group’: a collection of
threads all launched in response to the same event. The Project
maintains a list of ‘live’ thread-groups. (DOC TODO: Better word than
‘live’? Means ‘at least one non-zombie thread’.)</p>
<p>An event can be exogenous (keypress, green-flag) or endogenous
(broadcast — although for testing have ability to exogenously do
broadcast).</p>
<p>Pytch does not immediately launch threads on a keypress or mouse click.
These events are stored in a queue, and then processed at the start of
each frame. It simplifies the testing slightly to have the main
one-frame code pull new events from the keyboard and mouse.</p>
</section>
<section id="generation-of-events">
<h2>Generation of events<a class="headerlink" href="#generation-of-events" title="Link to this heading">¶</a></h2>
<p>Exogenous events:</p>
<ul class="simple">
<li><p>Green flag click has explicit entry point in Project,
on_green_flag_clicked()</p></li>
<li><p>when-I-receive: also message string; stored as map with message
string as key.</p></li>
<li><p>Keypresses: stored in a ‘keyboard’ and drained at the start of each
frame</p></li>
<li><p>Mouse clicks: likewise</p></li>
</ul>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../webapp/user/index.html">Using the Pytch web app</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user/index.html">Writing Pytch programs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../about.html">About Pytch</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../developer.html">Developer documentation</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../developer/development-setup.html">Development setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/design-overview.html">Design overview</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="index.html">VM</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="overview.html">Overview</a></li>
<li class="toctree-l3"><a class="reference internal" href="integration-with-client.html">Integration with client</a></li>
<li class="toctree-l3"><a class="reference internal" href="based-on-skulpt.html">Skulpt: Python / JavaScript bridge</a></li>
<li class="toctree-l3"><a class="reference internal" href="project.html">Project</a></li>
<li class="toctree-l3"><a class="reference internal" href="actor.html">Actor: Sprite and Stage</a></li>
<li class="toctree-l3"><a class="reference internal" href="actor-registration.html">Actor-class registration</a></li>
<li class="toctree-l3"><a class="reference internal" href="threading-model.html">Threading model</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">Hat blocks</a></li>
<li class="toctree-l3"><a class="reference internal" href="syscalls.html">Syscalls</a></li>
<li class="toctree-l3"><a class="reference internal" href="skulpt-pytch-environment.html">Skulpt API / Pytch environment</a></li>
<li class="toctree-l3"><a class="reference internal" href="testing.html">Testing</a></li>
<li class="toctree-l3"><a class="reference internal" href="ide-web-app.html">Web-app</a></li>
<li class="toctree-l3"><a class="reference internal" href="rendering.html">Rendering</a></li>
<li class="toctree-l3"><a class="reference internal" href="hit-detection.html">Collision and click detection</a></li>
<li class="toctree-l3"><a class="reference internal" href="clones.html">Clones</a></li>
<li class="toctree-l3"><a class="reference internal" href="sounds.html">Sounds</a></li>
<li class="toctree-l3"><a class="reference internal" href="tutorials.html">Tutorials</a></li>
<li class="toctree-l3"><a class="reference internal" href="docstrings.html">Docstrings</a></li>
<li class="toctree-l3"><a class="reference internal" href="attribute-watchers.html">Watching object attributes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../webapp/developer/index.html">Webapp</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../medialib/developer/index.html">Media library</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/index.html">Website</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../build-tools/index.html">Tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../source-build.html">Source and build information</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../releases/changelog.html">Changelog</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../legal/index.html">Legal information</a></li>
</ul>
<div class="docs-home-link"><hr>
  <ul>
    <li>
      <a href="../../index.html">Pytch help home</a>
    <li>
  </ul>
</div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
  </body>
</html>